Using Forms

Using Forms to Collect Name Information

If you want to use different names each time you run the sample automation, manually adjusting the MyFirstName and MyLastName variable tasks would rebuild the automation each time, but it would also be highly inefficient. As a solution, it would be far better to leave the automation "as is" and simply provide the name values when you run the automation. To accomplish this, you will need to use a JSON Form.

Likewise, running the automation from Automation Studio every time would not only be tedious but also require manual alterations that could unwittingly open the door to automation errors. To avoid this scenario, you will need to kick off the automation via JSON Form using Automation Catalog.

The docs.itential.com site contains more detailed user guides specific to Automation Catalog and JSON Forms

Access Automation Catalog

From the IAP home page:

1. Click the Automation Catalog tile. The main page displays.

2. Click + CREATE AN AUTOMATION.

   Note: The "automation" terminology used here is somewhat of a misnomer. You won't actually be creating an automation as you did in Automation Studio. Instead you'll be providing access to an automation that's already built.

3. Give your automation the name "GenerateFacts".

4. Optionally provide a description.

5. Click the CREATE button.

In the GenerateFacts Automation Catalog window:

1. Select the "EnlightenMe" automation from the Automation list.
2. Click SAVE (lower-left corner).
3. Under the Form list, click the + NEW FORM button.
4. A pop-up message may display asking you to confirm if you want to leave the site.
5. Accept the prompt. Doing so will open the JSON Form Builder.

Create a JSON Form

To create your JSON Form:

1. Go to the upper-left corner of the canvas.
2. For the Form name, add "GenFacts".
3. Click the CREATE button that appears under the name field.
4. Click the SAVE button that appears after you create the form.
5. Go the list of Form Elements on the right side.
6. Click and drag the TEXT INPUT element onto the canvas.
7. Click the cog icon to the right of TEXT INPUT.
8. Label the text element "FirstName".
9. Select "Yes" under the Required setting to make the "FirstName" label a required field.
10. Click SAVE.
11. Add another TEXT INPUT element and label it "LastName".
12. Make the "LastName" label a required field.
13. Click SAVE.
14. Click GO BACK TO AUTOMATION CATALOG at the bottom of the form.

Figure 1. JSON Form

For more information on building forms, refer to the JSON Forms user guide on the docs.itential.com site.

Save the JSON Form

Once you build the JSON Form, you will return to the Automation Catalog entry "GenerateFacts" that was started earlier.

1. In the Form list, select the "GenFacts" form you created.
2. Click SAVE.

Now let's take a moment and do a checkpoint.

So far, you have created an Automation Catalog entry that will display a newly built "GenFacts" form. Next, you will need to send the form values to the "EnlightenMe" automation, but keep in mind, the automation isn't expecting to receive input from a form. In this part of the process, you will need to update the automation to use the entry values from the JSON Form instead of the "New Variable" tasks -- MyFirstName and MyLastName.

Update the Automation to Accept Form Inputs

To update the automation:

1. Click the App Grid icon in the header toolbar.

   Figure 2. App Grid

   

2. Select "Automation Studio" from the list.

3. Click the "Find Automation" option (center of screen).

4. Find the "EnlightenMe" automation tile.

5. Click the menu icon (lower-right corner of the tile).

6. Select Edit.

   Figure 3. Edit Automation

   

You are now back on the familiar Automation Builder canvas.

Set the Query Tasks

At this point, you will need to switch out the task data for "MyFirstName" and "MyLastName". The intent here is to consume the information from the GenFacts form instead of the hard-coded values contained in the "New Job Variable" tasks.

1. Click the "MyFirstName" task.

2. Click the Delete button, or the trashcan icon (upper-right corner) on the canvas, to delete the task.

3. Repeat the previous step for the "MyLastName" task. Your canvas is now missing two necessary variables.

4. In the Task Menu Sidebar, search for "Query".

5. Add two Query tasks to the canvas (to replace the tasks just deleted).

6. Add a transition from the FactURL to one of the new Query tasks.

7. Double-click the Query task to edit the properties.

8. Change the Summary to "Form-FirstName".

9. Change the Description to a short comment that will make sense in the canvas tooltip. For example: "Isolate FirstName from form".

   The tool tip description should be clear and give the user a hint as to the purpose of that specific task.

10. Set the pass_on_null Reference task variable to "False".

11. Set the query Reference task variable to "firstName", which is the name of the field in the JSON Form you created.

    For compliance purposes, the "FirstName" field label on the "GenFacts" form is automatically converted to camelCase, making it firstName instead.

Change the Object Variable

You will need to change the obj variable manually:

1. Change the Reference task to job.
2. For the Reference variable, click the EDIT button.
3. Manually type the word "formData" (without quotes and case-senstive).
4. Click outside of the text entry box when finished.
5. Click SAVE to return to the canvas.

The first Query task is now configured to understand that it will be obtaining content from a JSON form. Now let's move on to the second Query task.

1. Add a transition from the "Form-FirstName" query task that was just altered to the second Query task you added.

2. Configure the second Query task to be "Form-LastName".

   This query variable will search for lastName. Remember, the "LastName" field label is converted to camelCase on the "GenFacts" form.

3. Set the pass_on_null variable to "False".

4. Notice that formData is now an option in the job variable list for obj. Select it from the list.

5. Add a transition from the "Form-LastName" query task to the FirstName-Update (replace) task.

You should now have a series of nine workflow tasks on the canvas.

1. START
2. FactURL
3. Form-FirstName (Query)
4. Form-LastName (Query)
5. FirstName-Update
6. LastName-Update
7. FetchFact
8. Query (IsolateFact)
9. END

Figure 4. Workflow Tasks

Update the Replace Tasks

Next, you will need to update the replace tasks to consume and work with the form values collected in the Query tasks you added.

1. Update the Firstname-Update task properties:
   • Set the newSubstr Reference task variable to the "Form-FirstName" task.
   • The Reference variable should automatically change to return_data.
2. Click Save.
3. Update the Lastname-Update task properties:
   • Set the newSubstr variable Reference task to the "Form-LastName" task.
   • The Reference variable should automatically change to return_data.
4. Click Save.

Note: After updating all the tasks, you could try to manually run the automation, but it will likely result in an error. This is because the automation is now expecting input from a JSON form; however, up until now you have not directly indicated "what form" the automation should expect input values from. You'll recall that the form name was specified within the "GenerateFacts" entry in Automation Catalog.

Test Run the Automation Catalog Entry

1. At this point, you should have saved the entire automation.

2. Click the App Grid icon in the header toolbar.

3. Select "Automation Catalog" from the list of options.

4. Click Find Automation.

5. Find the "GenerateFacts" automation tile.

6. Click the Play icon (lower-right corner).

7. The "GenFacts" form displays in a modal window.

8. Provide FirstName and LastName values.

9. Click START (lower-left corner). The modal window is replaced with a Run Automation notification window.

   Figure 5. Notification Message

   

10. Click the VIEW JOB button to open the Job Manager page.

11. Find the IsolateFact task in the job list.

12. Click the book icon to view the OUTGOING value.

You should observe that "Chuck Norris" has been replaced by whatever name input you gave in the "GenerateFacts" Automation (form) initiated from Automation Catalog.

Summary Wrap-Up

Kudos, what great work you've done! You completed all the sections of this quick start tour from start to finish. Let's review all that you've accomplished on your journey:

• Created an automation that utilizes tasks to obtain data from a remote system.
• Viewed active jobs in Job Manager and navigate to the Outgoing tab to view task results.
• Used additional task inputs that interacted with values presented by other tasks in the automation.
• Customized an automation to accept user input.
• Created an Automation Catalog entry that uses a custom JSON Form to obtain input that's passed to an automation.

After completing this guide, you should be well on your way to using all the the basic capabilities of your IAP instance. To expand your knowledge further, refer to the Itential Automation Platform User Guides provided on the docs.itential.com site for more detailed information.